Using the REST Adapter for Sending Data

The REST (REpresentational State Transfer) Adapter provides data access to the Expeditor integrator runtime through HTTP. In addition to the messaging channel access, the REST Adapter allows for exchanging message content with Expeditor integrator, but uses HTTP. This is important for the integration of other not-messaging-based legacy systems (e.g. terminals, PDAs).

Figure 16 shows the REST Adapter architecture. The HTTP Request is taken and transformed into an Expeditor integrator compliant message. This message is then placed into the ReqInQ or CtrlQ in the same way as the messaging system would do it. From there on, the previous HTTP request is handled in the same way as any incoming message. The process of the HTTP request message is tracked in the Persistence Service. This information is taken to provide an appropriate status response to the initial HTTP Request.


Figure 16: HTTP requests based on the Expeditor integrator request schema can be used to send data to Expeditor integrator. These requests are converted into Expeditor integrator messages and are put into the ReqInQ (by default) for further processing.

All HTTP requests to the REST Adapter can be secured with username and password. Please, refer to the Installing and Configuring the IBM Lotus Expeditor integrator platform for configuration details.

HTTP Request Schema for REST Adapter

The REST resource for the Expeditor integrator REST interface is a Request. A Request in Expeditor integrator terms maps onto a request message as sent by the enterprise via JMS and the bridge. The HTTP URI scheme for a Request Resource is as follows:

/Integrator/Request/
where is the unique transaction identifier given by the requesting application. The Expeditor integrator context root is set in the configuration of the implementing Client Services Web Project.

Creating a new Request

As per standard REST semantics, the creation of a new integrator Request is made using an HTTP POST and the URI scheme from above. Within the HTTP request, the Expeditor integrator Request headers as defined for requests made via JMS are included in the HTTP headers, prefixed with IBMIntegrator-. For example, the following shows how the header would look for the TransferType header:

IBMIntegrator-TransferType: FTP

The following is the retail example for the Price Update request headers made using the REST interface:

Listing 15: HTTP Request header for Price Update request in the retail industry example.

 POST /Integrator/Request/12343 HTTP/1.1

User-Agent: ACME-REST-Client/1.0

IBMIntegrator-ResourceType: Price_Upd_File

IBMIntegrator-BuildInterval: 0

IBMIntegrator-MessagePurpose: FileTransfer

IBMIntegrator-EndOfData: true

IBMIntegrator-Description: ArticleFlowData

IBMIntegrator-SequenceNo: 0

IBMIntegrator-LocationId: Store_100

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Content-Type: text/plain

Content-Length: 2332

... 

Within the doPost() method of the Request Servlet, the HTTP headers will hence be read and the Expeditor integrator specific headers will be extracted to create the JMS message. Note, that all of the provided headers will be set as String properties on the JMS message. This means that the data format supplied in the HTTP headers must be a supported format for the data as it will be read on receipt e.g. numbers must be correctly formatted. In the above example, EndOfData JMS Custom Header property will be read from the JMS message on receipt as Boolean; therefore it must be set on the HTTP header in one of the supported Java string formats for a Boolean value (i.e. true or false). An exception will be thrown at runtime if the values cannot be translated.

Any payload for the request (such as the contents of a file) will be provided as the payload of the HTTP POST. The HTTP Content-Type header will be set as follows to indicate whether the data is binary or text:

• text/plain;charset=
  for encoded textual file content where is the character encoding for the payload, e.g. UTF-8.
• application/octet-stream
  for raw binary content.

For more information on HTTP content types, see http://en.wikipedia.org/wiki/Internet_media_type#List_of_common_media_types .

Note: The presence of the Content-Type header and the inclusion of the transaction identifier in the request URI means that any explicit Expeditor integrator TransferMode and TransactionId JMS Custom Header properties will be ignored to avoid confusion.

A successful HTTP request to create an Expeditor integrator Request will respond with an HTTP 200 OK response.

Case Insensitiveness of HTTP headers

Since the HTTP request headers are case in-sensitive, we can’t rely on the Lotus Expeditor Client WebContainer to retain the case. So, a mapping like below is needed:

	<param name="ibmxpdintegrator-messagepurpose" value="MessagePurpose" type="String"/>

	<param name="ibmxpdintegrator-buildinterval" value="BuildInterval" type="Long"/>

	<param name="ibmxpdintegrator-endofdata" value="EndOfData" type="Boolean"/> 

Please, refer to the Installing and Configuring the IBM Lotus Expeditor integrator platform for more configuration details (see ‎Ref_1).

Routing

Routing of the created messages by the Request Servlet (Figure 16) is done through the mapping between the MessagePurpose and JNDI key for a destination queue/topic, for example.

<routing>

	<messagepurpose value="FileTransfer" destination="jms/XPDinteg_ReqInQ"/>

	<messagepurpose value="HouseKeeping" destination="jms/XPDinteg_CtrlQ"/>

	…

</routing> 

Please, refer to the Installing and Configuring the IBM Lotus Expeditor integrator platform for more configuration details (see ‎Ref_1).

Querying the status of a Request

HTTP GET is used with the URI scheme described above to query the status of Expeditor integrator REST Request. No specific additional headers are required in the HTTP request. The response to a successful request is an HTTP 200 OK response with a Javascript Object Notation (JSON ) payload containing details of the status of the initial Request. JSON is a simple data format that is not only highly suitable for consumption by web browser applications but also by richer programming languages. For more information see http://www.json.org/ .

The JSON payload will be structured as follows:

 {

	status: “<transaction status>”

} 

where is the transaction status as returned by the Monitor Service (described elsewhere in this document). The HTTP Content-Type header will be set to application/json accordingly.

Error responses

For both POST and GET, error conditions will be indicated by giving an appropriate HTTP response code together with a JSON payload containing diagnostic information. The response will have an HTTP Content-Type header set to application/json and a payload structured as follows:

{

	message: “<diagnostic message>”

} 

where is a descriptive string to indicate the cause of the problem. A table of the HTTP response codes used specifically by the Expeditor integrator can be found in chapter ‎2.6.1.5.

REST Adapter Response Codes

For both POST and GET Requests, error conditions will be indicated by giving an appropriate HTTP response code and diagnostic information. Table 9 shows the HTTP response codes used specifically by Expeditor integrator.

Table 4: REST interface diagnostic message meaning

HTTP response code	Expeditor integrator meaning	diagnostic message
500	Internal Server error. An unexpected exception occurred when processing the REST request. The diagnostic message will contain any exception message and an entry should have been written to the error log.	Any exception messages caught by the REST interface.
404	Not found. Expeditor integrator could not find any record of the Request with the provided transaction identifier.	Could not find any record of the Request with the provided transaction identifier .
400	Bad request. The transaction identifier of the request is either missing or malformed.	The transaction identifier of the request is either missing or malformed.

Note: Other HTTP response codes may be returned by the Lotus Expeditor Client WebContainer. For example, if access control is implemented where upon a 403 response (forbidden) would occur for bad or missing credentials. Similarly, a malformed URI would result in a 404 response. In each of these cases, the payload would not be in JSON format. A full catalogue of HTTP response codes can be found at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html .